<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.5.2" />
<title>Gerrit Code Review - Installation Guide</title>
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #dddddd;
  color: #777777;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > div.content {
  white-space: pre;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}


@media print {
  div#footer-badges { display: none; }
}

div#toc {
  margin-bottom: 2.5em;
}

div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock-content {
  white-space: pre;
}
div.verseblock-attribution {
  padding-top: 0.75em;
  text-align: left;
}

div.exampleblock-content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      // Use [\s\S] in place of . so multi-line matches work.
      // Because JavaScript has no s (dotall) regex flag.
      note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      spans[i].innerHTML =
        "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
        "' title='View footnote' class='footnote'>" + n + "</a>]";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
}

}
/*]]>*/
</script>
</head>
<body>
<div id="header">
<h1>Gerrit Code Review - Installation Guide</h1>
<span id="revnumber">version 2.3</span>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<h2 id="requirements">Requirements</h2>
<div class="sectionbody">
<div class="paragraph"><p>To run the Gerrit service, the following requirements must be met on
the host:</p></div>
<div class="ulist"><ul>
<li>
<p>
JDK, minimum version 1.6 <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Download</a>
</p>
</li>
</ul></div>
<div class="paragraph"><p>You&#8217;ll also need a SQL database to house the review metadata. You have the
choice of either using the embedded H2 or to host your own MySQL or PostgreSQL.</p></div>
</div>
<h2 id="download">Download Gerrit</h2>
<div class="sectionbody">
<div class="paragraph"><p>Current and past binary releases of Gerrit can be obtained from
the downloads page at the project site:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="http://code.google.com/p/gerrit/downloads/list">Gerrit Downloads</a>
</p>
</li>
</ul></div>
<div class="paragraph"><p>Download any current <tt>*.war</tt> package. The war will be referred to as
<tt>gerrit.war</tt> from this point forward, so you may find it easier to
rename the downloaded file.</p></div>
<div class="paragraph"><p>If you would prefer to build Gerrit directly from source, review
the notes under <a href="dev-readme.html">developer setup</a>.</p></div>
</div>
<h2 id="createdb">Database Setup</h2>
<div class="sectionbody">
<h3 id="createdb_h2">H2</h3><div style="clear:left"></div>
<div class="paragraph"><p>During the init phase of Gerrit you will need to specify which database to use.
If you choose H2, Gerrit will automatically set up the embedded H2 database as
backend so no set up in advance is necessary.  Also, no additional configuration is
necessary.  Using the embedded H2 database is the easiest way to get a Gerrit
site up and running, making it ideal for proof of concepts or small team
servers.  On the flip side, H2 is not the recommended option for large
corporate installations. This is because there is no easy way to interact
with the database while Gerrit is offline, it&#8217;s not easy to backup the data,
and it&#8217;s not possible to set up H2 in a load balanced/hotswap configuration.</p></div>
<div class="paragraph"><p>If this option interests you, you might want to consider <a href="install-quick.html">the quick guide</a>.</p></div>
<h3 id="createdb_postgres">PostgreSQL</h3><div style="clear:left"></div>
<div class="paragraph"><p>This option is more complicated than the H2 option but is recommended
for larger installations. It&#8217;s the database backend with the largest userbase
in the Gerrit community.</p></div>
<div class="paragraph"><p>Create a user for the web application within Postgres, assign it a
password, create a database to store the metadata, and grant the user
full rights on the newly created database:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>  createuser -A -D -P -E gerrit2
  createdb -E UTF-8 -O gerrit2 reviewdb</tt></pre>
</div></div>
<h3 id="createdb_mysql">MySQL</h3><div style="clear:left"></div>
<div class="paragraph"><p>This option is also more complicated than the H2 option. Just as with
PostgreSQL it&#8217;s also recommended for larger installations.</p></div>
<div class="paragraph"><p>Create a user for the web application within the database, assign it a
password, create a database, and give the newly created user full
rights on it:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>  mysql

  CREATE USER 'gerrit2'@'localhost' IDENTIFIED BY 'secret';
  CREATE DATABASE reviewdb;
  ALTER DATABASE reviewdb charset=latin1;
  GRANT ALL ON reviewdb.* TO 'gerrit2'@'localhost';
  FLUSH PRIVILEGES;</tt></pre>
</div></div>
</div>
<h2 id="init">Initialize the Site</h2>
<div class="sectionbody">
<div class="paragraph"><p>Gerrit stores configuration files, the server&#8217;s SSH keys, and the
managed Git repositories under a local directory, typically referred
to as <tt>'$site_path'</tt>.  If the embedded H2 database is being used,
its data files will also be stored under this directory.</p></div>
<div class="paragraph"><p>You also have to decide where to store your server side git repositories. This
can either be a relative path under <tt>'$site_path'</tt> or an absolute path
anywhere on your server system. You have to choose a place before commencing
your init phase.</p></div>
<div class="paragraph"><p>Initialize a new site directory by running the init command, passing
the path of the site directory to be created as an argument to the
<em>-d</em> option.  Its recommended that Gerrit Code Review be given its
own user account on the host system:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>  sudo adduser gerrit2
  sudo su gerrit2

  java -jar gerrit.war init -d /path/to/your/gerrit_application_directory</tt></pre>
</div></div>
<div class="paragraph"><p><em>Please note:</em> If you choose a location where your new user doesn&#8217;t
have any privileges, you may have to manually create the directory first and
then give ownership of that location to the <tt>'gerrit2'</tt> user.</p></div>
<div class="paragraph"><p>If run from an interactive terminal, the init command will prompt through a
series of configuration questions, including gathering information
about the database created above.  If the terminal is not interactive,
running the init command will choose some reasonable default selections,
and will use the embedded H2 database. Once the init phase is complete,
you can review your settings in the file <tt>'$site_path/etc/gerrit.config'</tt>.</p></div>
<div class="paragraph"><p>When running the init command, additional JARs might be downloaded to
support optional selected functionality.  If a download fails a URL will
be displayed and init will wait for the user to manually download the JAR
and store it in the target location.</p></div>
<div class="paragraph"><p>When the init phase is complete, the daemon will be automatically started
in the background and your web browser will open to the site:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>  Initialized /home/gerrit2/review_site
  Executing /home/gerrit2/review_site/bin/gerrit.sh start
  Starting Gerrit Code Review: OK
  Waiting for server to start ... OK
  Opening browser ...</tt></pre>
</div></div>
<div class="paragraph"><p>When the browser opens, sign in to Gerrit through the web interface.
The first user to sign-in and register an account will be
automatically placed into the fully privileged Administrators group,
permitting server management over the web and over SSH.  Subsequent
users will be automatically registered as unprivileged users.</p></div>
</div>
<h2 id="_installation_complete">Installation Complete</h2>
<div class="sectionbody">
<div class="paragraph"><p>Your base Gerrit server is now installed and running.  You&#8217;re now ready to
either set up more projects or start working with the projects you&#8217;ve already
imported.</p></div>
</div>
<h2 id="project_setup">Project Setup</h2>
<div class="sectionbody">
<div class="paragraph"><p>See <a href="project-setup.html">Project Setup</a> for further details on
how to register a new project with Gerrit.  This step is necessary
if existing Git repositories were not imported during <em>init</em>.</p></div>
</div>
<h2 id="rc_d">Start/Stop Daemon</h2>
<div class="sectionbody">
<div class="paragraph"><p>To control the Gerrit Code Review daemon that is running in the
background, use the rc.d style start script created by <em>init</em>:</p></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="literalblock">
<div class="content">
<pre><tt>review_site/bin/gerrit.sh start
review_site/bin/gerrit.sh stop
review_site/bin/gerrit.sh restart</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>(<em>Optional</em>) Link the gerrit.sh script into rc3.d so the daemon
automatically starts and stops with the operating system:</p></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="literalblock">
<div class="content">
<pre><tt>sudo ln -snf `pwd`/review_site/bin/gerrit.sh /etc/init.d/gerrit.sh
sudo ln -snf ../init.d/gerrit.sh /etc/rc3.d/S90gerrit</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>To install Gerrit into an existing servlet container instead of using
the embedded Jetty server, see
<a href="install-j2ee.html">J2EE installation</a>.</p></div>
</div>
<h2 id="customize">Site Customization</h2>
<div class="sectionbody">
<div class="paragraph"><p>Gerrit Code Review supports some site-specific customization options.
For more information, see the related topic in this manual:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="config-reverseproxy.html">Reverse Proxy</a>
</p>
</li>
<li>
<p>
<a href="config-sso.html">Single Sign-On Systems</a>
</p>
</li>
<li>
<p>
<a href="config-replication.html">Git Replication/Mirroring</a>
</p>
</li>
<li>
<p>
<a href="config-headerfooter.html">Site Header/Footer</a>
</p>
</li>
<li>
<p>
<a href="config-gitweb.html">Gitweb Integration</a>
</p>
</li>
<li>
<p>
<a href="config-gerrit.html">Other System Settings</a>
</p>
</li>
</ul></div>
</div>
<h2 id="anonymous_access">Anonymous Access</h2>
<div class="sectionbody">
<div class="paragraph"><p>Exporting the Git repository directory
(<a href="config-gerrit.html#gerrit.basePath">gerrit.basePath</a>) over the
anonymous, unencrypted git:// protocol is more efficient than
Gerrit&#8217;s internal SSH daemon.  See the <tt>git-daemon</tt> documentation
for details on how to configure this if anonymous access is desired.</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html">man git-daemon</a>
</p>
</li>
</ul></div>
</div>
<h2 id="_external_documentation_links">External Documentation Links</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
<a href="http://www.postgresql.org/docs/">PostgreSQL Documentation</a>
</p>
</li>
<li>
<p>
<a href="http://dev.mysql.com/doc/">MySQL Documentation</a>
</p>
</li>
<li>
<p>
<a href="http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html">git-daemon</a>
</p>
</li>
</ul></div>
</div>
<hr style="
  height: 2px;
  color: silver;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
">
<div class="paragraph"><p>Part of <a href="index.html">Gerrit Code Review</a></p></div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Version 2.3<br />
Last updated 2012-02-22 13:16:35 MDT
</div>
</div>
</body>
</html>
